Add TimeZone header support to REST API (#17344) by Lexert19 · Pull Request #17387 · apache/iotdb

Lexert19 · 2026-03-29T00:01:04Z

Description

This PR adds support for the TimeZone header in REST API. The header is parsed in AuthorizationFilter and the time zone is set in the session. Integration tests are added to verify correct handling of valid and invalid time zones.

Closes #17344

This PR has:

Key changed/added classes (or packages if there are too many classes) in this PR

HTHou · 2026-03-30T01:36:23Z

Add support in
https://github.com/apache/iotdb/blob/master/external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/table/v1/impl/RestApiServiceImpl.java and https://github.com/apache/iotdb/blob/master/external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v1/impl/RestApiServiceImpl.java ?

HTHou · 2026-03-30T02:03:19Z

Another question, why did you pick X-TimeZone? I found there is a document uses Time-Zone.
https://docs.github.com/en/rest/using-the-rest-api/timezones-and-the-rest-api?apiVersion=2026-03-10#using-the-time-zone-header

HTHou · 2026-03-30T02:10:09Z

And consider add some example in https://github.com/apache/iotdb/tree/master/example/rest-java-example/src/main/java/org/apache/iotdb?

Lexert19 · 2026-04-03T12:25:03Z

Hi @HTHou, thank you for the review! I've updated the PR:

Renamed the header to Time-Zone
Added support for V1 and Table V1 API
Added examples
Added integration tests for V1 and V2, following the existing code style

HTHou · 2026-04-05T00:48:05Z

Hi @Lexert19, could you please share this new feature in the dev mail list?

Copilot

Pull request overview

This PR introduces request-level time zone handling for the REST APIs by parsing a time zone HTTP header in the REST authorization filter, storing it on the session, and then using the session ZoneId when parsing SQL statements so time literals (and time-based semantics like GROUP BY window alignment) respect the client-provided time zone.

Changes:

Parse a time zone header in AuthorizationFilter and set the resolved ZoneId into the SessionManager session (reject invalid values with HTTP 400).
Use the current session ZoneId (instead of ZoneId.systemDefault()) when generating statements in REST v1/v2 and Grafana REST implementations (and table REST statement creation).
Add integration tests and update Java REST examples to demonstrate header usage.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
integration-test/src/test/java/org/apache/iotdb/db/it/IoTDBRestServiceIT.java	Adds IT coverage for valid/invalid time zone headers on REST v1/v2 query and nonQuery flows.
external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v2/impl/RestApiServiceImpl.java	Uses session `ZoneId` when parsing SQL for v2 query/nonQuery endpoints.
external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v2/impl/GrafanaApiServiceImpl.java	Uses session `ZoneId` when parsing Grafana SQL endpoints in v2.
external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v1/impl/RestApiServiceImpl.java	Uses session `ZoneId` when parsing SQL for v1 query/nonQuery endpoints.
external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v1/impl/GrafanaApiServiceImpl.java	Uses session `ZoneId` when parsing Grafana SQL endpoints in v1.
external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/table/v1/impl/RestApiServiceImpl.java	Uses the client session’s `ZoneId` when parsing table-model SQL statements.
external-service-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/filter/AuthorizationFilter.java	Parses `Time-Zone` header into `ZoneId`, aborts request on invalid values, and supplies it to the session.
example/rest-java-example/src/main/java/org/apache/iotdb/TableHttpsExample.java	Adds a table REST query example that includes a time zone header.
example/rest-java-example/src/main/java/org/apache/iotdb/TableHttpExample.java	Adds a table REST query example that includes a time zone header and uses slf4j logging.
example/rest-java-example/src/main/java/org/apache/iotdb/HttpsExample.java	Adds a REST query example that includes a time zone header.
example/rest-java-example/src/main/java/org/apache/iotdb/HttpExample.java	Adds a REST “queryWithTimeZone” example (but currently missing the actual header).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

integration-test/src/test/java/org/apache/iotdb/db/it/IoTDBRestServiceIT.java

...rvice-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/filter/AuthorizationFilter.java

example/rest-java-example/src/main/java/org/apache/iotdb/HttpExample.java

Lexert19 · 2026-04-09T21:10:32Z

Hi @HTHou, i have updated the PR to address all the feedback:
-Integration Tests: Adjusted test timestamps to ensure they fall within the GROUP BY time window.
-AuthorizationFilter: Added .trim() to the Time-Zone header to avoid errors with extra spaces.
-Example: Added the missing Time-Zone header to HttpExample.java.

Lexert19 force-pushed the f_timezone_header branch from dacddb6 to 4eb0e06 Compare April 3, 2026 12:17

Lexert19 changed the title ~~Add X-TimeZone header support to REST API (#17344)~~ Add TimeZone header support to REST API (#17344) Apr 3, 2026

Lexert19 force-pushed the f_timezone_header branch from 4eb0e06 to a286e68 Compare April 3, 2026 12:41

HTHou requested a review from Copilot April 8, 2026 02:43

Copilot started reviewing on behalf of HTHou April 8, 2026 02:43 View session

Copilot AI reviewed Apr 8, 2026

View reviewed changes

Lexert19 added 4 commits April 9, 2026 22:57

Add X-TimeZone header support to REST API (apache#17344)

a70e434

Support Time-Zone header and add examples for REST API

76801e8

fix test resource leaks

cb9cd5c

copilot review

1c7b835

Lexert19 force-pushed the f_timezone_header branch from f0c638e to 1c7b835 Compare April 9, 2026 21:00

HTHou requested review from CritasWang and JackieTien97 April 10, 2026 04:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add TimeZone header support to REST API (#17344)#17387

Add TimeZone header support to REST API (#17344)#17387
Lexert19 wants to merge 4 commits intoapache:masterfrom
Lexert19:f_timezone_header

Lexert19 commented Mar 29, 2026 •

edited by HTHou

Loading

Uh oh!

HTHou commented Mar 30, 2026 •

edited

Loading

Uh oh!

HTHou commented Mar 30, 2026

Uh oh!

HTHou commented Mar 30, 2026

Uh oh!

Lexert19 commented Apr 3, 2026 •

edited

Loading

Uh oh!

HTHou commented Apr 5, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Lexert19 commented Apr 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Lexert19 commented Mar 29, 2026 • edited by HTHou Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Key changed/added classes (or packages if there are too many classes) in this PR

Uh oh!

HTHou commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

HTHou commented Mar 30, 2026

Uh oh!

HTHou commented Mar 30, 2026

Uh oh!

Lexert19 commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

HTHou commented Apr 5, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Lexert19 commented Apr 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Lexert19 commented Mar 29, 2026 •

edited by HTHou

Loading

HTHou commented Mar 30, 2026 •

edited

Loading

Lexert19 commented Apr 3, 2026 •

edited

Loading